home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 4 / Meeting Pearls Vol. IV (1996)(GTI - Schatztruhe)[!].iso / Pearls / dev / c / C-Interpreter / CInt.doc < prev    next >
Text File  |  1995-05-31  |  10KB  |  275 lines
  1.  
  2. Since this is not the final docs (they are done in TeX), this is just a
  3. small draft.
  4.  
  5. Overview
  6. --------
  7.  
  8. The C-interpreter (CI from now on) uses a BOOPSI-like interface, that is
  9. you can create Code-objects, store source in it and can execute it with
  10. a special method. Here is a short example:
  11.  
  12.     Object * code;
  13.  
  14.     code = CInt_NewObject (NULL, CINTCLASS
  15.     , CIA_Source, "printf (\"Hello World\\n\");"
  16.     , CIA_StaticString, TRUE
  17.     , TAG_END);
  18.  
  19. This example is the infamous hello.c. It creates a code object, stores
  20. a statement in it (CIA_Source). Since the source is a static string
  21. (it is not freed before the object), the resource CIA_StaticString
  22. is set to TRUE which saves a couple of bytes.
  23.  
  24.     There is a CInt_SetAttr(), CInt_GetAttr(), CInt_DoMethod() and
  25. CInt_Dispose(). For this release, I use my own interface (ie. all
  26. standard BOOPSI functions are available with the prefix "CInt_"),
  27. since I need global data (shared by all processes on the system)
  28. and data unique to each process. When I find a good solution (hints
  29. are welcome !), the interface may change (ie. I will use the
  30. real functions and install a public class). If that happens, I will
  31. provide #define's so you still don't have to change your code.
  32.  
  33.     The next important step is to execute the code in the object:
  34.  
  35.     int rc;
  36.     Value result;
  37.  
  38.     rc = CInt_DoMethod (code, CIM_Execute, &result);
  39.  
  40. This executes the source stored in the object. The result of the
  41. last operation (eg. return or the last expression) is stored in
  42. <result>. <rc> is the return code which is defined to be compatible
  43. with the shell: 0 means no error, 5 means warning, 10 means error
  44. and 20 means something severe (if you access memory outside the valid
  45. bounds, this is NOT thought of beeing severe ! That's just an error...
  46. You get the idea).
  47.  
  48. Here follows a BOOPSI-compatible description of the class:
  49.  
  50. BOOPSI Class Interface
  51. ----------------------
  52.  
  53. Class:        cintclass
  54. Superclass:    rootclass
  55. Include File:    <interpreter/cint.h>
  56.  
  57. ANSI-C compatible interpreter. The objects contains source which can be
  58. executed. The source can contains predefined functions (like printf())
  59. or user-defined C-compiled functions or user-defined interpreted functions
  60. plus most standard C-stuff.
  61.  
  62. New Methods:
  63. ------------
  64.  
  65. int CIM_Execute (Value * result) - Execute the current contents of the
  66.     object. The result of the last expression is stored in <result> if
  67.     it is non-NULL. If the pointer is non-NULL, it is initialised by
  68.     the method (ie. it is not neccessary to initialize it with
  69.     CInt_InitValueStruct()).
  70.  
  71.     The result is the current error-code of the interpreter. (See
  72.     CIA_ErrorCode below).
  73.  
  74. int CIM_SetSymbolValue (STRPTR name, Value * value) - Set the value of
  75.     a variable in the interpreter.
  76.  
  77.     NOTE: The interpreter uses implicit type-casting very extensively.
  78.     Thus it is not neccessary that the type of <value> matches the type
  79.     of the symbol. If <value> is an int-type and the variable <name>
  80.     is a string, the value is converted into a string internally and
  81.     then assigned to <name>.
  82.  
  83. Changed Methods:
  84. ----------------
  85.  
  86. The methods OM_SET and OM_GET return the current value of the attribute
  87. CIA_ErrorCode.
  88.  
  89. Attributes:
  90. -----------
  91.  
  92. CIA_Replace (BOOL, ISG) Defines whether the definition of a new global
  93.     variable should replace an old variable with the same name.
  94.  
  95.     Default: FALSE
  96.  
  97. CIA_IOMode (LONG, ISG) The source can be stored in a string or a file.
  98.     If this is set to IOM_STRING, then the value following CIA_Source
  99.     must be a string; for IOM_FILE it has to be a valid FILE*-pointer
  100.     (the latter is not implemented yet *sigh*).
  101.  
  102.     Default: IOM_STRING
  103.  
  104. CIA_Source (APTR, IS) The source to store in the object. If you set this
  105.     twice, all memory associated with the former source is freed. The
  106.     type of this attribute is specified with CIA_IOMode.
  107.  
  108. CIA_StaticString (BOOL, ISG) Normally, the object creates a copy
  109.     of the source if it is a string. But if you are sure that the
  110.     memory for the string stays valid all the time until the object
  111.     is freed, you can save a couple of bytes if you set this to
  112.     TRUE.
  113.  
  114.     Default: FALSE
  115.  
  116. CIA_ErrorCode (ULONG *, IG) Use this to query the state of the interpreter.
  117.     Most functions return this value as return-value. After an error,
  118.     the class is in an exceptional state and most functions will
  119.     fail immediately until you query this attributs. By reading it,
  120.     the interpreter tells you what is wrong and resets itself. Querying
  121.     this attribute does NOT change CIA_ErrorMessage so you can still
  122.     get the list of error-messages afterwards (eg. in another routine
  123.     where you handle errors).
  124.  
  125.     The following values are possible:
  126.  
  127.     0   Everything is fine
  128.     5   During the execution of the last command, some warnings
  129.         have been generated. This should not be harmful; most
  130.         functions will still work.
  131.     10  Something serious has happened which means that the
  132.         execution of the last command had to be aborted. After
  133.         querying the attribute, everything should be as it was
  134.         before you executed the last command.
  135.     20  If you get this back, you are a miracle worker ! It means
  136.         that the code was just about to crash. I try to terminate
  137.         execution by calling exit(), but there is not much chance
  138.         that it will work.
  139.  
  140.     NOTE: Reading this attribute resets it.
  141.  
  142.  
  143. CIA_ErrorMessage (STRPTR **, IG) This is to get a list of all warnings
  144.     and errors created by the last operation. Every message is a pointer
  145.     in the array which is NULL-terminated.
  146.  
  147.     If you are done with processing the messages, you have to free them
  148.     with CInt_FreeErrorMessages().
  149.  
  150.     NOTE: Reading this attribute clears it. If there has not been an
  151.     error, you get NULL back.
  152.  
  153.     NOTE2: It is not possible to set this attribute, but you can
  154.     specify it at creation time.
  155.  
  156.     NOTE3: This attribute is ALWAYS a pointer to STRPTR* ! If you
  157.     specify it at creation time, the interpreter will WRITE the
  158.     error messages into it, so you can find out what went wrong
  159.     even when there is no object yet.
  160.  
  161. CIA_UserData (ULONG, ISG) This is for you. You can do whatever you
  162.     want with it. For now, there is no way to access this field inside
  163.     the interpreted code, sorry.
  164.  
  165. CIA_Version (ULONG, G) This is the current version of the CI. The upper
  166.     16 bits contain the version, the lower 16 bits the revision.
  167.  
  168. CIA_VersionString (STRPTR, G) Like CIA_Version, but returns the version
  169.     string as defined in the Amiga developer material.
  170.  
  171. Convenience Functions
  172. ---------------------
  173.  
  174. CInt_InitValueStruct() - This function is neccessary to initialize
  175.     a Value-structure before you can use it to give values into the
  176.     interpreter (eg. for the CIM_SetSymbolValue-Method).
  177.  
  178. CInt_ExecuteString() - Executes the contents of a string. Use it like
  179.     this:
  180.  
  181.     STRPTR * errs;
  182.     int      rc;
  183.     int      t;
  184.  
  185.     rc = CInt_ExecuteString ("printf (\"Hello world.\\n\");", &errs);
  186.  
  187.     if (rc != RETURN_OK) /* Error ? */
  188.     {
  189.     fprintf (stderr, "There have been errors/warnings:\n");
  190.  
  191.     for (t=0; errs[t]; t++)
  192.         fputs (errs[t], stderr);
  193.  
  194.     CInt_FreeErrorMessages (errs);
  195.     }
  196.  
  197. CInt_AddGlobalSymbols() - Add user-defined global symbols to the
  198.     interpreter. These variables are shared by all processes (ie. you
  199.     can use them to exchange data).
  200.  
  201.     The only parameter of the function is an SymDef-array. This array
  202.     consists of a series of declarations and addresses. A declaration
  203.     describes a new global variable (in this case the address is NULL),
  204.     or a new global function (like printf()); here the address is the
  205.     address of the function. Here a short example from the actual code:
  206.  
  207.     { "int printf (string, ...);",  (APTR) printf   },
  208.     { "int GlobalInt;",             NULL            },
  209.     { NULL,                     }
  210.  
  211.     As you can see, this is really a prototype of the function printf()
  212.     (well, mostly... C does not know about the type "string"). You can
  213.     add any function by simply giving the prototype and the address
  214.     (but you should make sure that the function is available during
  215.     the lifetime of the class since you can't remove it yet... oh well)
  216.  
  217.     The second line shows how to declare a new global variable (in fact,
  218.     you can define any number of variables in one line as you can in C;
  219.     for functions this does not work since I need the address).
  220.  
  221.     The NULL in the last line terminates the list.
  222.  
  223. CInt_FreeErrorMessages() - This function must be used to free all memory
  224. associated with an array of error messages (as returned by CIA_ErrorMessage
  225. or CInt_ExecuteString()).
  226.  
  227. Installation
  228. ------------
  229.  
  230.     copy libs/cint.library libs:
  231.  
  232. or
  233.  
  234.     assign libs: libs add
  235.  
  236. If you want to compile the example, there is no need to copy the includes
  237. over your include-files; the SCOPTIONS-file searches the files in this
  238. directory.
  239.  
  240. Examples
  241. --------
  242.  
  243. The file ci_test.c is a short, but complete example, for the use of the
  244. CI. The directory test/ contains a bunch of example programs that can
  245. be executed directly with ci_test. I use them myself to test the interpreter.
  246. Here are some highlights:
  247.  
  248.     tfor.c - a for-loop which counts up and down and prints the
  249.         counter with printf()
  250.     top.c - a test for all C-operators.
  251.     ttime.c - an example for using systems functions.
  252.  
  253. These are the most important, but there are more. The example program
  254. ci_test.c can be compiled with SAS/C 6.51 (which I use right now; dunno
  255. about DICE since I didn't had the time to test it. Sorry again).
  256.  
  257. If you have questions, examples, support code (eg. the complete amiga
  258. Gfx-library in SymDef-format), write to me at:
  259.  
  260.     Aaron Digulla
  261.     Th.-Heuss-Str 8
  262.     78467 Konstanz
  263.  
  264. or (preferred)
  265.  
  266.     digulla@fh-konstanz.de
  267.  
  268. If you send snail-mail, include an envelope with stamp and your address or
  269. you will wait quite some time for an answer (would you spend $$$ for
  270. answering mail form australia ? ;)
  271.  
  272. Don't expect an answer until 26.6.95 since I'm on hollidays until then :)
  273.  
  274. Amiga makes it possible.
  275.